Public Class Map

Code Sample

• %REM
  The following code filters out values that are odd numbers
  %END REM
  Class EvenFilter as MapFilter
      Function filter(kvPair as Pair) as Boolean
          Dim value as Integer
          value = kvPair.value
          Return value Mod 2 = 0
      End Function
  End Class
  Dim map as New Map("INTEGER", Nothing, False)
  Dim ef as New EvenFilter
  Dim map2 as Map
  Call map.put("Elem1", 1)
  Call map.put("Elem2", 2)
  Call map.put("Elem3", 3)
  Call map.put("Elem4", 4)
  Set map2 = map.filter(ef)
  Print map2.elementCount

Properties Detail

• comparator (Get)

  Public Property Get comparator As Comparator
  Comparator to compare keys with.

• contentType (Get)

  Public Property Get contentType As String
  Content-Type of values within the map

• elementCount (Get)

  Public Property Get elementCount As Long
  Number of elements in the map

• hasContent (Get)

  Public Property Get hasContent As Boolean
  Flag indicating if the Map has elements

• isLocked (Get)

  Public Property Get isLocked As Boolean
  Flag indicating if the Map is locked

• isSorted (Get)

  Public Property Get isSorted As Boolean
  Flag indicating if the Map's keys are sorted

• suppressErrors (Get)

  Public Property Get suppressErrors As Boolean
  Suppress errors on adding or inserting elements. Errors wll still be thrown if the Map is locked or attempting to putting an element at an index into a sorted Map. Instead of throwing an error, e.g. for wrong content type, the method will just return false

• suppressErrors (Set)

  Public Property Set suppressErrors As Boolean
  Suppress errors on adding or inserting elements. Errors wll still be thrown if the Map is locked or attempting to putting an element at an index into a sorted Map. Instead of throwing an error, e.g. for wrong content type, the method will just return false

Methods Detail

• clone

  Public Function clone() As Map
  Creates a clone of the Map.
  Code Sample
  Dim map1 as New Map("STRING", Nothing, False) Dim map2 as Map Call map1.put("Hello","World") Set map2 = map1.clone()

• collectKeys

  Public Function collectKeys() As Collection
  Returns a clone of the keys in this Map.
  Code Sample
  %REM The following code creates a Map of US state abbreviations and full names. If a list of only abbreviations is needed for another purpose, collectKeys() can be used to quickly get it. %END REM Dim map as New Map("STRING", Nothing, False) Dim coll as Collection Call map.add("CO","Colorado") Call map.add("CA","California") Set coll = map.collectKeys()

• collectValues

  Public Function collectValues(targetColl As Collection) As Collection
  Loads the values from this Map into the passed Collection.
  idx	Argument	Data Type	Attributes	Comments
  1	targetColl	Collection		Collection into which to add the values from this Map
  Code Sample
  %REM The following code creates a Map of US state abbreviations and full names. If a list of just state names sorted alphabetically is needed for another purpose, collectValues() can be used to get it. %END REM Dim map as New Map("STRING", Nothing, False) Dim coll as New Collection("STRING", Nothing, False, True) Call map.add("CO","Colorado") Call map.add("CA","California") Call map.collectValues(coll)

• contains

  Public Function contains(checkValue As Variant, valueComparator As Comparator) As Boolean
  Checks whether the Map contains a specific value.
  idx	Argument	Data Type	Attributes	Comments
  1	checkValue	Variant		Value to check for
  2	valueComparator	Comparator		Comparator to use to check vale
  Code Sample
  Dim map as New Map("STRING", Nothing, False) Dim compar as MatchingDataTypeComparator Call map.add("CO","Colorado") Call map.add("CA","California") Print map.contains("California") ' Prints True Print map.contains("CALIFORNIA") ' Prints False

• containsKey

  Public Function containsKey(keyVal As Variant) As Boolean
  Checks whether the Map contains a specific key.
  idx	Argument	Data Type	Attributes	Comments
  1	keyVal	Variant		Value to check for
  Code Sample
  %REM The following code creates a Map of US state abbreviations and full names. If a list of only abbreviations is needed for another purpose, collectKeys() can be used to quickly get it. %END REM Dim map as New Map("STRING", Nothing, False) Call map.add("CO","Colorado") Call map.add("CA","California") Print map.contains("CO") ' Prints True Print map.contains("WA") ' Prints False

• filter

  Public Function filter(filterObj As MapFilter) As Map
  Filters a Map using a mapFilter and returns a new "filtered" Map.
  idx	Argument	Data Type	Attributes	Comments
  1	filterObj	MapFilter		Map filter to check each key and value with
  Code Sample
  %REM The following code filters out values that are odd numbers %END REM Class EvenFilter as MapFilter Function filter(kvPair as Pair) as Boolean Dim value as Integer value = kvPair.value Return value Mod 2 = 0 End Function End Class Dim map as New Map("INTEGER", Nothing, False) Dim ef as New EvenFilter Dim map2 as Map Call map.put("Elem1", 1) Call map.put("Elem2", 2) Call map.put("Elem3", 3) Call map.put("Elem4", 4) Set map2 = map.filter(ef) Print map2.elementCount

• getAndRemoveFirstPair

  Public Function getAndRemoveFirstPair() As Pair
  Gets and removes the first key/value Pair.
  Code Sample
  Dim map as New Map("INTEGER", Nothing, False) Dim pair as Pair Call map.put("Elem1", 1) Call map.put("Elem2", 2) Call map.put("Elem3", 3) Call map.put("Elem4", 4) Set pair = map.getAndRemoveFirstPair() Print pair.value ' Prints 1
  Throws Exceptions
  Message	Error Code	Comments
  Map is locked	1403

• getAndRemoveLastPair

  Public Function getAndRemoveLastPair() As Pair
  Gets and removes the last key/value Pair
  Code Sample
  Dim map as New Map("INTEGER", Nothing, False) Dim pair as Pair Call map.put("Elem1", 1) Call map.put("Elem2", 2) Call map.put("Elem3", 3) Call map.put("Elem4", 4) Set pair = map.getAndRemoveLastPair() Print pair.value ' Prints 4
  Throws Exceptions
  Message	Error Code	Comments
  Map is locked	1403

• getNthKeyRaw

  Public Function getNthKeyRaw(index As Long) As Variant
  Returns the key at a particular index
  idx	Argument	Data Type	Attributes	Comments
  1	index	Long		Index of key to get, starting at 0
  Code Sample
  Dim map as New Map("INTEGER", Nothing, False) Call map.put("Elem1", 1) Call map.put("Elem2", 2) Call map.put("Elem3", 3) Call map.put("Elem4", 4) Print CStr(map.getNthKey(2)) ' Prints "Elem3"

• getNthPair

  Public Function getNthPair(index As Long) As Pair
  Returns the element at the relevant index as a key/value Pair
  idx	Argument	Data Type	Attributes	Comments
  1	index	Long		Index at which to find the element
  Code Sample
  Dim map as New Map("INTEGER", Nothing, False) Dim pair as Pair Call map.put("Elem1", 1) Call map.put("Elem2", 2) Call map.put("Elem3", 3) Call map.put("Elem4", 4) Set pair = map.getNthPair(2) Print "Third pair is " & pair.key & ", " & pair.value

• getNthValueRaw

  Public Function getNthValueRaw(index As Long) As Variant
  Gets the value at a particular index. If no matching value is found, the return type will depend on the content defined. If the Map contains objects, the return value is Nothing. If the Map contains scalars, the return value is an empty variant.
  idx	Argument	Data Type	Attributes	Comments
  1	index	Long		Index of the value to get, starting at 0
  Code Sample
  Dim map as New Map("INTEGER", Nothing, False) Dim returnVal as Integer Call map.put("Elem1", 1) Call map.put("Elem2", 2) Call map.put("Elem3", 3) Call map.put("Elem4", 4) returnVal = CInt(map.getNthElementRaw(2)) Print "Value is " & returnVal

• getValueRawByKey

  Public Function getValueRawByKey(keyVal As Variant) As Variant
  Gets a value from the Map for the passed key. If the Map contains objects, the return type is Nothing. If the Map contains scalars, the return type is an empty variant.
  idx	Argument	Data Type	Attributes	Comments
  1	keyVal	Variant		Key of value to get
  Code Sample
  Dim map as New Map("INTEGER", Nothing, False) Dim returnVal as Variant Call map.put("Elem1", 1) Call map.put("Elem2", 2) Call map.put("Elem3", 3) Call map.put("Elem4", 4) returnVal = map.getValueRawByKey("Elem3")

• put

  Public Function put(key As Variant, value As Variant) As Long
  Puta an element in the Map.
  idx	Argument	Data Type	Attributes	Comments
  1	key	Variant		Scalar value to use as the key
  2	value	Variant		Value to put into the Map
  Code Sample
  Dim map as New Map("INTEGER", Nothing, False) Call map.put("Elem1", 1) Call map.put("Elem2", 2)
  Throws Exceptions
  Message	Error Code	Comments
  Map is locked	1403
  If incorrect data type is passed	1400

• putAll

  Public Function putAll(source As Map) As Map
  Puts all entries from a Map into this map
  idx	Argument	Data Type	Attributes	Comments
  1	source	Map		Map to copy into this Map
  Code Sample
  Dim map as New Map("INTEGER", Nothing, False) Dim map2 as New Map("INTEGER", Nothing, False) Call map.put("Elem1", 1) Call map.put("Elem2", 2) Call map.put("Elem3", 3) Call map2.putAll(map)
  Throws Exceptions
  Message	Error Code	Comments
  Map is locked	1403
  If incorrect data type is passed	1400

• putPair

  Public Function putPair(content As Pair) As Long
  Puts a Pair into the Map, using key as the key and value as the Value.
  idx	Argument	Data Type	Attributes	Comments
  1	content	Pair		Pair to insert
  Code Sample
  Dim map as New Map("INTEGER", Nothing, False) Dim pair as New Pair("Elem3", 3) Call map.put("Elem1", 1) Call map.put("Elem2", 2) Call map.putPair(pair)
  Throws Exceptions
  Message	Error Code	Comments
  Map is locked	1403
  If incorrect data type is passed	1400

• removeByKey

  Public Function removeByKey(keyVal As Variant) As Boolean
  Removes an element from the Map based on its key.
  idx	Argument	Data Type	Attributes	Comments
  1	keyVal	Variant		Key of element to remove
  Code Sample
  Dim map as New Map("INTEGER", Nothing, False) Call map.put("Elem1", 1) Call map.put("Elem2", 2) Call map.put("Elem3", 3) Call map.put("Elem4", 4) Set map2 = map.removeByKey("Elem1")
  Throws Exceptions
  Message	Error Code	Comments
  Map is locked	1403

• removeByValue

  Public Function removeByValue(value As Variant, allMatches As Boolean, valueComparator As Comparator) As Boolean
  Removes a value or values from the Map
  idx	Argument	Data Type	Attributes	Comments
  1	value	Variant		Value to remove
  2	allMatches	Boolean		Whether to remove all matches or just the first match
  3	valueComparator	Comparator		Comparator to use to check value
  Code Sample
  Dim map as New Map("INTEGER", Nothing, False) Dim comparator as MatchingDataTypeComparator Call map.put("Elem1", 1) Call map.put("Elem2", 2) Call map.put("Elem3", 2) Call map.put("Elem4", 4) Call map.put("Elem3", 2) Call map.removeByValue(2, False, comparator) Print map.elementCount ' Prints 4 Call map.removeByValue(2, True, comparator) Print map.elementCount ' Prints 2
  Throws Exceptions
  Message	Error Code	Comments
  Map is locked	1403

• toJson

  Public Function toJson() As JsonObject
  Converts the Map to a JsonObject. If the values are objects, the code will try to call a toJson method on the object, otherwise skip them.
  Code Sample
  Dim map as New Map("INTEGER", Nothing, False) Dim jsonObj as jsonObject Call map.put("Elem1", 1) Call map.put("Elem2", 2) Call map.put("Elem3", 3) Call map.put("Elem4", 4) Set jsonObj = map.toJson() Print jsonObj.toString(false) ' Prints {"Elem1":1,"Elem2":2,"Elem3":3,"Elem4":4}

• clear

  Public Sub clear()
  Removes all keys and values from the Map and resets whether the keyset is reversed.
  Code Sample
  Dim map as New Map("STRING",Nothing,False) Call map.put("Hello","World") Print map.hasContent ' Prints True Call map.clear() Print map.hasContent ' Prints False
  Throws Exceptions
  Message	Error Code	Comments
  Map is locked	1403

• fromJson

  Public Sub fromJson(jsonObj As JsonObject)
  Loads a JsonObject that contains an object of scalars into the Map
  idx	Argument	Data Type	Attributes	Comments
  1	jsonObj	JsonObject		JsonObject to put in the map
  Code Sample
  Dim map as New Map("SCALAR", Nothing, False) Dim parser as New JsonParser() Call parser.loadFromJson(|{"firstName":"John","lastName":"Doe","age":42}|) Call map.fromJson(parser.getRootObject())

• lock

  Public Sub lock()
  Locks the map, so any put, remove, replace or reverse fiunctions trigger errors. Useful when passing a Map to other functions.
  Code Sample
  %REM The following code throws error 403, "Map is locked" on the final line %END REM Dim map as New Map("INTEGER", Nothing, False) Call map.put("Elem1", 1) Call map.put("Elem2", 2) Call map.put("Elem3", 3) Call map.lock() Call map.put("Elem4", 4)

• New

  Public Sub New(contentType As String, keyComparator As Comparator, isSorted As Boolean)
  Constructor
  idx	Argument	Data Type	Attributes	Comments
  1	contentType	String		Defines the Content Type of the values in the Map
  2	keyComparator	Comparator		Comparator to determine order of keys
  3	isSorted	Boolean		Flag indicatin if the keys within the Map shall be sorted

• reverse

  Public Sub reverse()
  Reverses the keySet colection of a Map.
  Code Sample
  Dim map as New Map("INTEGER", Nothing, False) Call map.put("Elem1", 1) Call map.put("Elem2", 2) Call map.put("Elem3", 3) Call map.put("Elem4", 4) Call map.reverse() Print map.getNthKeyRaw(0) ' Prints "Elem4"
  Throws Exceptions
  Message	Error Code	Comments
  Map is locked	1403

• transform

  Public Sub transform(transformer As MapTransformer, newMap As Map)
  Transforms members of this Map usig a MapTransformer and adds them to the new Map passed.
  idx	Argument	Data Type	Attributes	Comments
  1	transformer	MapTransformer		MapTrasformer to transform members
  2	newMap	Map		Map to load transformed members into
  Code Sample
  %REM The following code swaps key and value over %END REM Class SwapTransformer as MapTransformer Function transform(kvPair as Pair) as Pair Return new pair(kvPair.value, kvPair.key) End Function End Class Dim map as New Map("INTEGER", Nothing, False) Dim map2 as New Map("STRING", Nothing, False) Dim transformer as New SwapTransformer() Call map.put("Elem1", 1) Call map.put("Elem2", 2) Call map.put("Elem3", 3) Call map.put("Elem4", 4) Call map.transform(transformer, map2) Print CStr(map2.getNthKeyRaw(0)) ' Prints 1

• unlock

  Public Sub unlock()
  Unlocks the Map, so put, remove, replace and reverse functions can be used again
  Code Sample
  Dim map as New Map("INTEGER", Nothing, False) Call map.put("Elem1", 1) Call map.put("Elem2", 2) Call map.put("Elem3", 3) Call map.lock() Try Call map.put("Elem4", 4) Catch If Err = 403 Then Print "Map was locked" End Try Call map.unlock() Call map.put("Elem4", 4) ' Successful